Document copy-db's blob companion directory and restore steps - #620
Document copy-db's blob companion directory and restore steps#620kriszyp wants to merge 1 commit into
Conversation
copy-db now writes the database's blob roots to `<target>-blobs/<rootIndex>/` and refuses a target that already exists (HarperFast/harper#2048). Blob files live outside the database file and are addressed by database name, so a copy is not restorable without them — document the layout, the restore steps for restoring under a different name, and that copy compaction is LMDB-only. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the documentation for the harper copy-db command and database compaction, adding details about file-backed blobs, target path constraints, and database engine applicability (LMDB vs. RocksDB). The review feedback suggests adding <VersionBadge> elements to properly document these behavior changes on existing surfaces, following repository guidelines.
|
|
||
| This copies the default `data` database to a new location with compaction applied. | ||
|
|
||
| The database's file-backed blobs are copied to `<target-database-path>-blobs/<rootIndex>/`, since blob files live outside the database file and are addressed by database name. The copy cannot be restored without that directory — see [Database Compaction](../database/compaction.md#file-backed-blobs-travel-separately) for the restore steps. LMDB databases only; RocksDB databases compact themselves. |
There was a problem hiding this comment.
According to the repository's guidelines, when documenting behavior changes to an existing surface (such as the new blob copying behavior and RocksDB exclusion in copy-db), we should use the <VersionBadge type="changed" version="vX.Y.0" /> format. Please add the appropriate version badge (e.g., v5.3.0 or the target release version) to indicate this change.
| The database's file-backed blobs are copied to `<target-database-path>-blobs/<rootIndex>/`, since blob files live outside the database file and are addressed by database name. The copy cannot be restored without that directory — see [Database Compaction](../database/compaction.md#file-backed-blobs-travel-separately) for the restore steps. LMDB databases only; RocksDB databases compact themselves. | |
| <VersionBadge type="changed" version="v5.3.0" /> — The database's file-backed blobs are copied to <target-database-path>-blobs/<rootIndex>/, since blob files live outside the database file and are addressed by database name. The copy cannot be restored without that directory — see [Database Compaction](../database/compaction.md#file-backed-blobs-travel-separately) for the restore steps. LMDB databases only; RocksDB databases compact themselves. |
References
- Use the format when documenting behavior changes to existing surface, as prescribed in the repository's guidelines.
|
|
||
| ### File-backed blobs travel separately | ||
|
|
||
| A database's file-backed blob values (`Blob` and large `Bytes` attributes) are not stored inside the database file. They live in the configured blob roots — `storage.blobPaths[n]`, or `<rootPath>/blobs/<database>` when `blobPaths` is not configured — and are addressed by **database name**, not by the path of the database file. |
There was a problem hiding this comment.
According to the repository's guidelines, when documenting behavior changes to an existing surface (such as the new file-backed blobs behavior), we should use the <VersionBadge type="changed" version="vX.Y.0" /> format. Please add the appropriate version badge (e.g., v5.3.0 or the target release version) to indicate this change.
| A database's file-backed blob values (`Blob` and large `Bytes` attributes) are not stored inside the database file. They live in the configured blob roots — `storage.blobPaths[n]`, or `<rootPath>/blobs/<database>` when `blobPaths` is not configured — and are addressed by **database name**, not by the path of the database file. | |
| <VersionBadge type="changed" version="v5.3.0" /> — A database's file-backed blob values (Blob and large Bytes attributes) are not stored inside the database file. They live in the configured blob roots — storage.blobPaths[n], or <rootPath>/blobs/<database> when blobPaths is not configured — and are addressed by **database name**, not by the path of the database file. |
References
- Use the format when documenting behavior changes to existing surface, as prescribed in the repository's guidelines.
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-620 This preview will update automatically when you push new commits. |
DavidCockerill
left a comment
DavidCockerill
left a comment
There was a problem hiding this comment.
Approving. No findings.
"The copy is not restorable without this directory" in bold is the sentence that matters, and it is not hedged. Anyone who took a copy-db backup before this was written could reasonably believe they hold a restorable copy and not.
The <rootIndex> explanation earns its length: preserving the source root's position is what lets a multi-root database restore each root to its original slot, and writing a README.md into the directory recording the mapping means the copy carries its own restore instructions rather than depending on someone finding this page later. Showing the restore under a different database name is also the case people actually hit.
The LMDB-only scope appears in both the CLI reference and the compaction page, so a reader arriving from either gets it.
— DAIvid (Claude Opus 5)
2 participants
Companion to HarperFast/harper#2098 (fixes HarperFast/harper#2048).
copy-dbpreviously left the database's file-backed blobs behind, so a copy moved to another host, or restored under a different database name, silently lost every blob. It now copies each blob root to<target>-blobs/<rootIndex>/alongside the database file, and refuses a target that already exists rather than merging the copy into it.Documents:
<rootIndex>layout, and the restore steps (including restoring under a different database name, which is where the blob roots have to be placed by hand)Generated by Claude Opus 5.